compile by Michael F. Kamprath, <mailto:kamprath@kagi.com>
co-author, John C. Daub, <mailto:hsoi@eden.com>
Version 1.2.2
This is a library of object handlers written in C designed for the WASTE Text Engine (by Marco Piovanelli). This library is designed to be "drop and play," requiring very few mandatory calls by your WASTE based application.
To use this library, either add the source to your project, or, if you are using CodeWarrior, add the proper enclosed CodeWarrior library to your project. It currently supports three types of objects: PICTs, sounds, and files. The only header you need to include in the rest of your application's code (where appropiate) is WASTE_Objects.h.
One additional point: be sure to include any required resources (such as the sound icon) in your project file. Some object handlers depend on them. If you decide to compile this archive yourself (you are using THINK C or something else), you will need to tell your compiler where the WASTE.h header file is as it is not included it in this archive (you will find it in the WASTE archive).
This archive requires WASTE 1.2 or later. WASTE can be found at <ftp://rhino.harvard.edu/pub/dan/WASTE/>
Object Handler Initialization
There are two mandatory calls that your application needs to make at initialization time to load all the object handlers into the WASTE engine:
This routine will load all appropiate handlers into the WASTE engine and intialize them (if need be). If it returns an error, not all handlers were loaded properly. You can pass a valid WASTE instance to install all the object handlers into a particular WASTE instance. If you wish to install all the object handlers globally, pass nil.
void InitWASTEObjectHandlers( void )
This routine will perform all the necessary internal initialization needed by the library. Call this at application intialization/startup. If you want the handlerﾕs sound channel to be created at initilization, define CREATE_CHANNEL_AT_INIT in WE_snd_Handler.h to 1. If you want the object handler to wait until the sound channel is actually needed, define CREATE_CHANNEL_AT_INIT to 0.
There is one mandatory call that your application needs to make at shutdown/quitting time:
void ExitWASTEObjectHandlers( void )
This routine will perform all the necessary internal cleanup needed by the library. Call this just before your application quits.
Other Handler Routines
Pictures
OSErr InstallPICTObject( WEReference theWE )
Use this routine if you wish to install the PICT object handler alone. Pass a WEReference to install into a particular WASTE instance, or pass nil to install globally.
Sounds
This library's method of implementing sound objects allows them to be played asynchronously. To do this, several support routines have been implemented for your use. Also, ICN# resource of ID 550 is used to provide the symbol for a sound object. Two icons have been provided in this archive to choose from (or you can design your own).
OSErr InstallSoundObject( WEReference theWE )
Use this routine if you wish to install the sound object handler alone. Pass a WEReference to install into a particular WASTE instance, or pass nil to install globally.
void CheckSoundStatus( void )
This routine checks the current sound status and, if need be, deallocates any sound buffer that is no longer in use. This routine must be called periodically (ideally in the event loop). However, as of the v1.2 release of the handler library, the need for you to call this routine is no longer necessary. The functionality of this routine has been incorporated into DoObjectTasks(), and you should call that function instead. Any existing calls to CheckSoundStatus() should be changed to call DoObjectTasks(). CheckSoundStatus() has been left as a public routine in the v1.2.x release to ease transition, but most likely in future releases, it will no longer be public in lieu of DoObjectTasks().
Boolean SoundIsPlaying( void )
Returns true if the sound shannel used by the sound object handler is currently playing a sound. Otherwise, it returns false.
OSErr PlaySelectedSound( WEReference theWE )
This routine causes the currently selected sound in a WASTE instance to be played. If no sound is selected, or if more "stuff" than just one sound is selected, nothing will happen.
OSErr StopCurrentSound( void )
Calling this routine immediately terminates the playing of the current sound (if one is playing).
OSErr CreateNewSoundObject( WEReference theWE )
This routine will use the built in sound input on the Mac to add a new sound object to a WASTE instance. It also will perform a Gestalt check to ensure that some sort of sound input device is available.
OSErr PlaySoundHandle( SndListHandle theSound )
This routine is made public in case your application will be playing other sounds outside of WASTE sound objects. This routine will play a sound handle on the same asyncnronous channel that the WASTE sound objects are. Please note that calling this routine copies the handle that is passed to it, so it is safe to dispose of the sound immediately after calling this routine.
Files
This library implements file onbjects with the same data that the Drag Manager describes a file with (HFSFlavor). This allows seamless interaction with the finder and allows users to just dragh a file from the finder to a window containing a WASTE instance to add a file object. To then open that file, the user just double clicks the file object in the WASTE instance and the Finder is sent an "Open Selection" apple event.
OSErr InstallHFSObject( WEReference theWE )
Use this routine if you wish to install the file object handler alone. Pass a WEReference to install into a particular WASTE instance, or pass nil to install globally.
This routine allows your application to insert a file object based on a passed file system specification record (typically obtained from a "Get File" dialog).
Object Handler Utilities
This library has some utility routines to help your application function properly when using these handlers.
OSErr DoObjectTasks( WEReference theWE )
This routine performs any and all internal object related tasks (such as checking the sound status). This routine must be called periodically (ideally in the main event loop). You can perform a task on a specific WASTE instance by passing that instance's WEReference. NOTE: for the v1.2.x release of the library, just pass nil. How this routine is used will change slightly in the future.
pascal OSErr WEObjectsPaste( WEReference hWE )
This routine is a replacement for WEPaste(); any time you call or would call WEPaste(), you should call this function instead. This routine allows special object scrap types to be handled properly by the library. If the scrap type does not need special handling (e.g. 'TEXT'), the call will fall through to WEPaste() and return the proper error code.
Please Read Onﾉ
Since this library is designed to be used with the WASTE text engine, this library shall fall under the same use license as the WASTE text engine. That is, if you satisfy the use license of the WASTE text engine as outlined by Marco Piovanelli, the you are free to use this library in your application.
If you have some other object handlers that you would like to include in this library, and agree to release it under the licensing scheme listed above, please forward it on to me (Michael Kamprath) and I will incorporate it as best as possible.
If you find any bugs in the current version of this library, or have an comments for improvement, please send me a note.
Some sample code on how to use this archive in ﾒadvancedﾓ ways is include in the Sample Code folder.
Release Info:
v1.0.0: (20 March 1995) Initial release.
v1.0.1: (21 March 1995) Update the object click handlers according to Marco Piovanelli's recomendations.
v1.0.2: (6 April 1995) Updated the archive for the WASTE 1.1a6 relese. Marco implemented a new method of registering object handlers.
v1.0.3: (16 April 1995) Happy Easter! Fixed two problems with file reference objects: 1) When using the InsertFileRefFromFSSpec() call, the icon would not be initially displayed correctly. 2) A crash when user drags a disk to a WASTE instance. For now, the file reference handler will display a generic hard drive in this situation. I will fix it later so that it will display the drive's actual icon. Just wanted to make it so that it doesn't crash in this release.
v1.0.4: (8 May 1995) Updated the installer routines to be compatible with WASTE v1.1a8 (CWASTE v1.1r12).
v1.0.5: (22 May 1995) Updated the headers of the object archive so that it can be compiled under older Symantec enviroments. Also added a gestalt check to CreateNewSoundObject() to ensure that some sort of sound input device is installed.
v1.1: (5 June 1995) Made several updates recomended by Chris Thomas <THUNDERONE@delphi.com>:
- Playing a sound object no longer makes a copy of the sound.
- API for stopping a ound and checking to see if one is playing.
- Option to create sound channel at handler initialization (compiler switch).
- Another optional icon design for sound object.
Also created routines to install individual object handlers.
v1.2: (1 April 1996) Happy April Fools Day! This release made by John Daub <mailto:hsoi@eden.com> while Michael is off busy with a new job in Germany. The updates/changes/fixes are from both John and Michael.
- Fixed a bug in SoundIsPlaying() that prevented the function from performing and returning correctly
- Fixed a related bug (to the above) in CheckSoundStatus() so now it functions properly
- Updated the archive to be consistant with WASTE 1.2a5
- Updated the project and object library files to CodeWarrior 8 and the latest Universal Headers
- Updated Michael's email address
- Modified the API to allow for easier and more flexible future expansion when new handlers are implimented:
- renamed the WE_Object_Init.c file to WASTE_Objects.c
- InstallAllWASTEObjHandlers() now takes a WEReference as an argument.
- Created InitWASTEObjectHandlers() and ExitWASTEObjectHandlers() to perform internal initializations, clean up, and any other internal startup/shutdown tasks
- Created DoObjectTasks() to 1. replace public calls to CheckSoundStatus() and 2. to handle any object periodic tasks (such as checking sound status or whatever future handlers might need)
- Created WEObjectsPaste() as a replacement for WEPaste() to allow for special object handling during pastes.
v1.2.1: (4 April 1996) John fixed a bug Rick Meier <meier@execusoft.com> pointed out. During HFS drags that the handler would have had to make an icon for (e.g. it wasn't a 'TEXT' file), the computer would freeze. Fixed a line in GetFileIcon.c where PBHGetVolParmsAsync() was being call when PBHGetVolParmsSync() should have been called. Works properly now. For the record, this was a bug I, John, accidentally introduced in the 1.2 release....oops.
v1.2.2: (16 July 1996) More of a maintanence release than anything else.
- Updated for CW9 (utilizing CW IDE 1.6.2)
- Updated for WASTE 1.2
- PPC Project: turned off processor specific instruction scheduling (no longer optimizes for 601, now just none).
- Handler initialization routines restructured to take advantage of C/C++ language differences. Plus, a little more robust in checks before installation (as per user requests). Thanx Marco for the syntax help!
